<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>specptrk</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="OpcodesTop.html" title="Orchestra Opcodes and Operators" />
    <link rel="prev" href="spechist.html" title="spechist" />
    <link rel="next" href="specscal.html" title="specscal" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">specptrk</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="spechist.html">Prev</a> </td>
          <th width="60%" align="center">Orchestra Opcodes and Operators</th>
          <td width="20%" align="right"> <a accesskey="n" href="specscal.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="refentry">
      <a id="specptrk"></a>
      <div class="titlepage"></div>
      <a id="IndexSpecptrk" class="indexterm"></a>
      <div class="refnamediv">
        <h2>
          <span class="refentrytitle">specptrk</span>
        </h2>
        <p>spectrk — 
      Estimates the pitch of the most prominent complex tone in the spectrum.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp150846848"></a>
        <h2>Description</h2>
        <p>
      Estimate the pitch of the most prominent complex tone in the spectrum.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp150848032"></a>
        <h2>Syntax</h2>
        <pre class="synopsis">koct, kamp <span class="command"><strong>specptrk</strong></span> wsig, kvar, ilo, ihi, istr, idbthresh, inptls, \
      irolloff [, iodd] [, iconfs] [, interp] [, ifprd] [, iwtflg]</pre>
      </div>
      <div class="refsect1">
        <a id="idp150914928"></a>
        <h2>Initialization</h2>
        <p>
      <span class="emphasis"><em>ilo, ihi, istr</em></span> -- pitch range conditioners (low, high, and starting) expressed in decimal octave form.
    </p>
        <p>
      <span class="emphasis"><em>idbthresh</em></span> -- energy threshold (in decibels) for pitch tracking to occur.  Once begun, tracking will be continuous until the energy falls below one half the threshold (6 dB down), whence the <span class="emphasis"><em>koct</em></span> and <span class="emphasis"><em>kamp</em></span> outputs will be zero until the full threshold is again surpassed. <span class="emphasis"><em>idbthresh</em></span> is a guiding value. At initialization it is first converted to the <span class="emphasis"><em>idbout</em></span> mode of the source spectrum (and the 6 dB down point becomes .5, .25, or 1/root 2 for modes 0, 2 and 3). The values are also further scaled to allow for the weighted partial summation used during correlation.The actual thresholding is done using the internal weighted and summed <span class="emphasis"><em>kamp</em></span> value that is visible as the second output parameter.
    </p>
        <p>
      <span class="emphasis"><em>inptls, irolloff</em></span> -- number of harmonic partials used as a matching template in the spectrally-based pitch detection, and an amplitude rolloff for the set expressed as some fraction per octave (linear, so don't roll off to negative).  Since the partials and rolloff fraction can affect the pitch following, some experimentation will be useful: try 4 or 5 partials with .6 rolloff as an initial setting; raise to 10 or 12 partials with rolloff .75 for complex timbres like the bassoon (weak fundamental). Computation time is dependent on the number of partials sought. The maximum number is 16.
    </p>
        <p>
      <span class="emphasis"><em>iodd</em></span> (optional) -- if non-zero, employ only odd partials in the above set (e.g. <span class="emphasis"><em>inptls</em></span> of 4 would employ partials 1,3,5,7). This improves the tracking of some instruments like the clarinet The default value is 0 (employ all partials).
    </p>
        <p>
      <span class="emphasis"><em>iconfs</em></span> (optional) -- number of confirmations required for the pitch tracker to jump an octave, pro-rated for fractions of an octave (i.e. the value 12 implies a semitone change needs 1 confirmation (two hits) at the <span class="emphasis"><em>spectrum</em></span> generating <span class="emphasis"><em>iprd</em></span>). This parameter limits spurious pitch analyses such as octave errors. A value of 0 means no confirmations required; the default value is 10.
    </p>
        <p>
      <span class="emphasis"><em>interp</em></span> (optional) -- if non-zero, interpolate each output signal (<span class="emphasis"><em>koct</em></span>, <span class="emphasis"><em>kamp</em></span>) between incoming <span class="emphasis"><em>wsig</em></span> frames. The default value is 0 (repeat the signal values between frames).
    </p>
        <p>
      <span class="emphasis"><em>ifprd</em></span> (optional) -- if non-zero, display the internally computed spectrum of candidate fundamentals.  The default value is 0 (no display).
    </p>
        <p>
      <span class="emphasis"><em>iwtftg</em></span> (optional) -- wait flag. If non-zero, hold each display until released by the user. The default value is 0 (no wait).
    </p>
      </div>
      <div class="refsect1">
        <a id="idp150929296"></a>
        <h2>Performance</h2>
        <p>
      At note initialization this unit creates a template of <span class="emphasis"><em>inptls</em></span> harmonically related partials (odd partials, if <span class="emphasis"><em>iodd</em></span> non-zero) with amplitude rolloff to the fraction <span class="emphasis"><em>irolloff</em></span> per octave. At each new frame of <span class="emphasis"><em>wsig</em></span>, the spectrum is cross-correlated with this template to provide an internal spectrum of candidate fundamentals (optionally displayed). A likely pitch/amp pair (<span class="emphasis"><em>koct</em></span>, <span class="emphasis"><em>kamp</em></span>, in decimal octave and summed <span class="emphasis"><em>idbout</em></span> form) is then estimated. <span class="emphasis"><em>koct</em></span> varies from the previous <span class="emphasis"><em>koct</em></span> by no more than plus or minus <span class="emphasis"><em>kvar</em></span> decimal octave units. It is also guaranteed to lie within the hard limit range <span class="emphasis"><em>ilo</em></span> -- <span class="emphasis"><em>ihi</em></span> (decimal octave low and high pitch). <span class="emphasis"><em>kvar</em></span> can be dynamic, e.g. onset amp dependent.  Pitch resolution uses the originating <span class="emphasis"><em>spectrum</em></span> <span class="emphasis"><em>ifrqs</em></span> bins/octave, with further parabolic interpolation between adjacent bins. Settings of root magnitude, <span class="emphasis"><em>ifrqs</em></span> = 24, <span class="emphasis"><em>iq</em></span> = 15 should capture all the inflections of interest. Between frames, the output is either repeated or interpolated at the k-rate. (See <a class="link" href="spectrum.html" title="spectrum"><em class="citetitle">spectrum</em></a>.)
    </p>
      </div>
      <div class="refsect1">
        <a id="idp150939616"></a>
        <h2>Examples</h2>
        <p>
      </p>
        <div class="informalexample">
          <pre class="programlisting">
  a1, a2   <span class="opc">ins</span>                                                           <span class="comment">; read a stereo clarinet input</span>
  krms     <span class="opc">rms</span>        a1, 20                                             <span class="comment">; find a monaural rms value</span>
  kvar     <span class="op">=</span>          0.6 <span class="op">+</span> krms<span class="op">/</span>8000                                    <span class="comment">; &amp; use to gate the pitch variance</span>
  wsig     <span class="opc">spectrum</span>   a1, 0.01, 7, 24, 15, 0, 3                          <span class="comment">; get a 7-oct spectrum, 24 bibs/oct</span>
           <span class="opc">specdisp</span>   wsig, 0.2                                          <span class="comment">; display this and now estimate</span>
  koct, ka <span class="opc">spectrk</span>    wsig, kvar, 7.0, 10, 9, 20, 4, 0.7, 1, 5, 1, 0.2   <span class="comment">; the pch and amp</span>
  aosc     <span class="opc">oscil</span>      ka <span class="op">*</span> ka <span class="op">*</span> 10, cpsoct(koct), 2                      <span class="comment">; &amp; generate \ new tone with these</span>
  koct     <span class="op">=</span>          (koct <span class="op">&lt;</span> 7.0 <span class="op">?</span> 7.0 <span class="op">:</span> koct)                          <span class="comment">; replace non pitch with low C</span>
           <span class="opc">display</span>    koct <span class="op">-</span> 7.0, 0.25, 20                               <span class="comment">; &amp; display the pitch track</span>
           <span class="opc">display</span>    ka, 0.25, 20                                       <span class="comment">; plus the summed root mag</span>
           <span class="opc">outs</span>       a1, aosc                                           <span class="comment">; output 1 original and 1 new track</span></pre>
        </div>
        <p>
    </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="spechist.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="OpcodesTop.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="specscal.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">spechist </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> specscal</td>
        </tr>
      </table>
    </div>
  </body>
</html>
